@x12i/editor 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 x12i
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,361 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @x12i/editor
+
+An accessible block editor for the Unified UI Kit, built on [Tiptap](https://tiptap.dev) v3 (MIT).
+
+The stored document is **JSON that the kit owns** (`EditorDocument`, versioned). Tiptap is only the
+engine that edits it: the editor converts to and from Tiptap/ProseMirror JSON at its edges, so the
+engine can be replaced without migrating saved documents.
+
+- Headings, lists, task lists, tables, callouts, toggles, columns, code, equations, images, video, audio,
+  files and bookmarks, plus the kit blocks: **chart**, **diagram**, **data view** and **AI block**.
+- Slash menu, markdown shortcuts, floating selection menu, toolbar, block menu, keyboard block moves.
+- Read-only `EditorView` that renders on the server.
+- Headless converters and exporters (HTML, Markdown, plain text, outline, diff, validation) that run anywhere.
+- Provider contracts for AI assistance (with a ready streaming UI) and collaboration (contract only).
+- Tokens-only styling (light, dark and high-contrast themes), RTL, i18n through a `messages` prop.
+
+## Install
+
+```sh
+pnpm add @x12i/editor @x12i/ui react react-dom
+```
+
+`@x12i/ui` and React are peer dependencies. The editor imports `Button`, `IconButton`, `Badge`, `Stack`,
+`Inline`, `Divider`, `Spinner` and `VisuallyHidden` from `@x12i/ui`. Wrap your app in the kit's
+`ThemeProvider` (and optionally `DensityProvider`) and load the editor stylesheet once:
+
+```ts
+import "@x12i/editor/styles.css";
+```
+
+## Two entry points
+
+| Import                       | Contents                                                                                   | Runs on the server |
+| ---------------------------- | ------------------------------------------------------------------------------------------ | ------------------ |
+| `@x12i/editor`               | Document schema and types, converters, exporters, outline, diff, validation, token helpers | Yes. No React, DOM or Tiptap imports. |
+| `@x12i/editor/react`         | `Editor`, `EditorView`, `EditorToolbar`, AI menu and hook, message helpers                 | `EditorView` yes; `Editor` renders `EditorView` until it mounts. |
+| `@x12i/editor/styles.css`    | The one stylesheet                                                                         | n/a                |
+
+`@x12i/editor/react` starts with `"use client"`, so it works from a Next.js server component tree as a
+client boundary. The root entry has no directive and no side effects.
+
+### Server-side rendering
+
+- `EditorView` is a pure render of the document. Use it in server components, static pages and email-like
+  output, and wherever people only read.
+- `Editor` creates its Tiptap instance with `immediatelyRender: false`: on the server and during hydration it
+  renders the same markup as `EditorView`, then swaps in the live editor after mount. No hydration mismatch,
+  no layout jump.
+- `documentToHtml(doc)` returns an HTML string with no React at all (all text is escaped, URLs are checked).
+
+## Quick start
+
+```tsx
+"use client";
+import { useState } from "react";
+import { createEmptyDocument, type EditorDocument } from "@x12i/editor";
+import { Editor } from "@x12i/editor/react";
+import "@x12i/editor/styles.css";
+
+export function Notes() {
+  const [doc, setDoc] = useState<EditorDocument>(() => createEmptyDocument());
+  return <Editor value={doc} onChange={setDoc} debounce={300} aria-label="Meeting notes" autoFocus />;
+}
+```
+
+`value` makes the editor controlled; `defaultValue` makes it uncontrolled. External changes to `value` are
+applied only when the new document differs from what the editor holds, and never fire `onChange`.
+
+### Read-only view
+
+```tsx
+import { EditorView } from "@x12i/editor/react";
+
+<EditorView value={doc} blockRenderers={blockRenderers} idPrefix="post-12-" />;
+```
+
+### Imperative API
+
+```tsx
+import { useRef } from "react";
+import type { EditorApi } from "@x12i/editor/react";
+
+const api = useRef<EditorApi>(null);
+
+<Editor ref={api} defaultValue={doc} />;
+
+api.current?.insertBlock("callout", { variant: "warning" });
+api.current?.exec("heading2");
+const markdown = api.current?.getMarkdown();
+```
+
+`onReady(api)` hands you the same object. `EditorApi`: `getDocument`, `setDocument`, `focus`, `insertBlock`,
+`exec`, `getMarkdown`, `getOutline`, `getEngine` (the raw Tiptap editor) and `announce`.
+
+## Charts, diagrams and data views: `blockRenderers`
+
+The editor **never imports** chart, diagram or data components. `@x12i/charts`, `@x12i/diagrams` and
+`@x12i/data` are used for **types only**. Embedded blocks are drawn by renderers you inject, so an app pays
+only for what it uses and the packages stay independent:
+
+```tsx
+import type { BlockRenderers } from "@x12i/editor/react";
+// Your app's own components: the editor does not care where they come from.
+import { MyChart, MyDiagram, MyDataView } from "./blocks";
+
+// Define at module level (or memoize): see "Renderer identity" below.
+const blockRenderers: BlockRenderers = {
+  chart: ({ payload, title }) => <MyChart spec={payload} aria-label={title} />, // payload: ChartSpec
+  diagram: ({ payload }) => <MyDiagram engine={payload.engine} document={payload.diagram} source={payload.source} />,
+  "data-view": ({ payload }) => <MyDataView dataset={payload.dataset} view={payload.view} />, // payload.view: SavedView
+};
+```
+
+Each renderer receives `{ type, id, payload, title, editable, selected }`. Payload types are exported as
+`EmbedPayloads`.
+
+Without a renderer, a block shows a tidy default card: a titled group with a summary and a "Show data"
+disclosure holding the JSON. That card is also what appears if a renderer throws (each renderer sits in an
+error boundary).
+
+### Editing and inserting embedded blocks
+
+```tsx
+<Editor
+  blockRenderers={blockRenderers}
+  onEditBlock={async (type, payload) => openChartDialog(type, payload) /* resolve the new payload, or null */}
+  onRequestBlock={async (type) => pickChart(type) /* resolve a payload, or null to cancel */}
+/>
+```
+
+Selecting an embedded block shows a small "Block tools" toolbar (Edit, Move up, Move down, Remove). Pressing
+Enter on a selected block calls `onEditBlock`. Choosing "Chart" in the slash menu calls `onRequestBlock`; if
+it is missing, the block is created with an empty payload and the default card.
+
+### Renderer identity
+
+Renderers are mounted as React components, so they may use hooks. Keep the functions stable (module level
+or `useMemo`): a new function identity on each render makes React remount that block and discard its state.
+
+## Supported blocks and marks
+
+| Document block (`type`)     | Tiptap node                         | Notes                                                                  |
+| --------------------------- | ----------------------------------- | ---------------------------------------------------------------------- |
+| `paragraph`                 | `paragraph`                         |                                                                        |
+| `heading` (level 1 to 4)    | `heading`                           |                                                                        |
+| `quote`                     | `blockquote`                        |                                                                        |
+| `callout` (`variant`)       | `callout` (custom)                  | info, success, warning, danger, neutral. `role="note"`.                |
+| `toggle`                    | `toggle` + `toggleSummary` (custom) | Disclosure button; Alt+Enter toggles.                                  |
+| `divider`                   | `horizontalRule`                    |                                                                        |
+| `bulleted-list`             | `bulletList` / `listItem`           | Nested.                                                                |
+| `numbered-list`             | `orderedList` / `listItem`          | Nested.                                                                |
+| `task-list`                 | `taskList` / `taskItem`             | Nested. Each checkbox is labelled with its text.                       |
+| `code` (`language`)         | `codeBlock` (custom)                | Language picker and copy button. No syntax highlighting.               |
+| `equation`                  | `equation` (custom)                 | LaTeX source shown as text. No math renderer bundled.                  |
+| `table`                     | `table`, `tableRow`, `tableHeader`, `tableCell` | Row/column menu; header row and column; col/row spans kept. |
+| `image`                     | `image` (custom view)               | Alt text required (or "decorative"), caption, alignment, width.        |
+| `video`, `audio`            | `media` (custom)                    | By URL; native controls.                                               |
+| `file`                      | `file` (custom)                     | Link card with name and size.                                          |
+| `bookmark`                  | `bookmark` (custom)                 | Link card.                                                             |
+| `columns`                   | `columns` / `column` (custom)       |                                                                        |
+| `page-break`                | `pageBreak` (custom)                | Breaks the page when printing.                                         |
+| `table-of-contents`         | `tableOfContents` (custom)          | Live list of headings.                                                 |
+| `chart`                     | `chart` (atom, injected renderer)   | Payload is a `ChartSpec`.                                              |
+| `diagram`                   | `diagram` (atom, injected renderer) | `engine` + `DiagramDocument` or `source`.                              |
+| `data-view`                 | `dataView` (atom, injected renderer)| `dataset` + `SavedView`.                                               |
+| `ai`                        | `aiBlock` (atom, injected renderer) | `prompt` + optional `result` blocks.                                   |
+| any other `type`            | `unknownBlock`                      | Kept untouched, reported as an `unknown-block` warning.                |
+
+| Inline                | Tiptap                         | Notes                                                                 |
+| --------------------- | ------------------------------ | --------------------------------------------------------------------- |
+| `bold`, `italic`, `strike`, `code` | `bold`, `italic`, `strike`, `code` |                                                  |
+| `underline`           | `underline`                    |                                                                       |
+| `link` (`href`)       | `link`                         | URL allow-list: see Security.                                         |
+| `color` (`token`)     | `textColor` (custom)           | Stores a token path, never a color value.                             |
+| `highlight` (`token`) | `highlight`                    | Stores a token path, never a color value.                             |
+| `mention`             | `mention` (custom)             | Existing mentions render; there is no picker.                         |
+| `emoji` (`shortcode`) | `emoji` (custom)               | Stored as a shortcode, rendered as the character with an accessible name. |
+
+## Markdown shortcuts
+
+Typed at the start of a block (then continue typing):
+
+| Type                          | Result                    |
+| ----------------------------- | ------------------------- |
+| `# `, `## `, `### `, `#### `  | Heading 1 to 4            |
+| `- `, `* `, `+ `             | Bulleted list             |
+| `1. `                         | Numbered list             |
+| `[ ] `, `[x] `                | Task list (unchecked, checked) |
+| `> `                          | Quote                     |
+| ```` ```ts ````, `~~~`        | Code block (language optional) |
+| `---`                         | Divider                   |
+
+Inline: `**bold**`, `*italic*` or `_italic_`, `~~strike~~`, `` `code` ``, and `:rocket:` for emoji.
+Pasted text keeps its formatting where Tiptap can parse it; URLs auto-link; unsafe URLs never become links.
+
+## Keyboard
+
+Modifier is Ctrl on Windows and Linux, Cmd on macOS.
+
+| Keys                           | Action                                                                |
+| ------------------------------ | --------------------------------------------------------------------- |
+| `/` at the start of a block or after a space | Open the slash menu                                     |
+| `ArrowDown` / `ArrowUp` (slash menu) | Move through blocks (wraps)                                     |
+| `Enter` or `Tab` (slash menu)  | Insert the highlighted block                                          |
+| `Escape` (slash menu)          | Close the menu and keep what you typed                                |
+| `Mod+/`                        | Open the block menu (turn into, duplicate, delete, move, add below)   |
+| `Alt+Shift+Up` / `Down`        | Move the current block up or down (announced to screen readers)       |
+| `Mod+K`                        | Add or edit a link                                                    |
+| `Mod+B`, `Mod+I`, `Mod+U`      | Bold, italic, underline                                               |
+| `Mod+Shift+S`, `Mod+E`         | Strikethrough, inline code                                            |
+| `Mod+Shift+7` / `8` / `9`      | Numbered, bulleted, task list                                         |
+| `Mod+Shift+B`                  | Quote                                                                 |
+| `Mod+Alt+C`                    | Toggle code block                                                     |
+| `Mod+Enter` (code block)       | Leave the code block                                                  |
+| `Tab` / `Shift+Tab` in a list  | Indent / outdent the item when that is possible; otherwise focus moves on. |
+| `Tab` / `Shift+Tab` in a table | Next / previous cell. `Tab` in the last cell adds a row; `Shift+Tab` in the first cell moves focus out. |
+| `Alt+Enter` (in a toggle)      | Expand or collapse                                                    |
+| `Enter` (embedded block selected) | Edit the block (`onEditBlock`)                                     |
+| `Mod+Z`, `Mod+Shift+Z`         | Undo, redo                                                            |
+| `Tab` to the toolbar, then `Left` / `Right`, `Home`, `End` | Toolbar is one tab stop with roving focus      |
+| `Escape` (menus, dialogs, bubble menu, AI menu) | Close and return to the text                         |
+
+## Accessibility
+
+The editor is built to the kit's accessibility rules (spec section 13) and tested with
+[axe](https://github.com/dequelabs/axe-core) in every tested state: editor with all blocks, toolbar, open
+menus, slash listbox, dialogs, embedded blocks, and the read-only view.
+
+- The editable area is `role="textbox"` with `aria-multiline="true"` and an accessible name
+  (`aria-label` / `aria-labelledby`, or the default from `messages`). The read-only editor is `role="document"`.
+- Not a keyboard trap in text: `Tab` moves focus out of the editor (it is only used to indent list items, move
+  between table cells and confirm a slash menu choice), and `Escape` always closes the open menu. In a table,
+  `Tab` in the last cell adds a row (the Tiptap default); leave a table with `Shift+Tab` from its first cell or
+  with the arrow keys, then `Tab` from the text after it.
+- The toolbar is a `role="toolbar"` with a roving tabindex (one tab stop, arrow keys inside). Toggle buttons
+  expose `aria-pressed`; disabled states are real `disabled`.
+- The slash menu is a `listbox`: the editor carries `aria-controls` and `aria-activedescendant` while it is
+  open, the options carry `aria-selected`, and result counts are announced through a polite live region.
+- Block moves, formatting changes, links, images, copy and AI results are announced in a status region.
+- Dialogs (link, image) trap focus, close on `Escape`, return focus to where they started, and validate with
+  `aria-invalid` + `aria-describedby` error text. Images require alternative text, or an explicit "decorative".
+- Focus rings use the kit's `--kit-color-border-focus` and `--kit-border-width-focus` tokens and are never
+  removed. Windows forced-colors and `prefers-reduced-motion` are handled in the stylesheet.
+- Color is never the only signal: callouts have a variant label, task state is a checkbox, and the text colors
+  and highlights on the allow-lists are chosen from the kit's contrast-checked foreground/background tokens.
+- RTL: only logical CSS properties; block elements use `dir="auto"` so right-to-left text mirrors lists, quotes
+  and tables. Code and equations are always `dir="ltr"`.
+
+## Theming
+
+All styling uses `--kit-*` design tokens, nothing is hard-coded. Every selector in `styles.css` is wrapped in
+`:where()` so it has zero specificity and is easy to override. Hooks for your own CSS:
+`[data-kit="editor"]`, `editor-toolbar`, `editor-content`, `editor-callout` (`data-variant`), `editor-toggle`
+(`data-open`), `editor-task-item` (`data-checked`), `editor-embed-block` (`data-embed`, `data-selected`),
+`editor-embed-card`, `editor-slash`, `editor-slash-option`, `editor-bubble`, `editor-dialog-form`, and so on. Dark mode and high contrast follow `ThemeProvider`. The editor
+defines only two private custom properties (`--kit-editor-x`, `--kit-editor-y`) for menu positioning.
+
+## Internationalization
+
+Every string comes from `messages`. Pass a partial override; missing keys fall back to English:
+
+```tsx
+import { Editor, defaultMessages, type DeepPartial, type Messages } from "@x12i/editor/react";
+
+const de: DeepPartial<Messages> = {
+  placeholder: "Schreibe etwas oder drücke / für Blöcke",
+  toolbar: { bold: "Fett", italic: "Kursiv" },
+  blocks: { heading1: { name: "Überschrift 1" } },
+};
+
+<Editor messages={de} locale="de" />;
+```
+
+Templates use ICU-style placeholders and `{count, plural, one {...} other {...}}` (via `Intl.PluralRules`
+with `locale`). Slash menu search ignores case and diacritics and matches names, descriptions and keywords in
+the active language. Helpers: `defaultMessages`, `mergeMessages`, `createTranslator`, `formatMessage`,
+`useMessages`, `useTranslator`.
+
+## AI assistance
+
+The kit calls no model. Provide an `AiProvider` (from the root entry) that streams text:
+
+```tsx
+import type { AiProvider } from "@x12i/editor";
+
+const aiProvider: AiProvider = {
+  async *run({ command, selection, tone, signal }) {
+    const response = await fetch("/api/ai", { method: "POST", body: JSON.stringify({ command, selection, tone }), signal });
+    if (!response.ok || !response.body) throw new Error(`Request failed (${response.status})`);
+    const decoder = new TextDecoder();
+    for await (const chunk of response.body) yield decoder.decode(chunk, { stream: true });
+  },
+};
+
+<Editor aiProvider={aiProvider} />;
+```
+
+With a provider, the toolbar and the selection menu show an "AI assistant" menu (improve, shorten, continue,
+fix spelling and grammar, ask with an instruction). The result streams into a **preview**; nothing changes the
+document until the person chooses Accept, and Stop or Reject discards it. Build your own surface with
+`useAiAssist({ provider, editor })` (status, preview, `run`, `accept`, `reject`, `cancel`) or `AiAssistMenu`.
+
+## Headless API (root entry)
+
+```ts
+import {
+  documentToTiptap, tiptapToDocument, // convert to and from the engine's JSON
+  documentToHtml, documentToMarkdown, documentToPlainText,
+  markdownToDocument,                 // import (GFM subset)
+  getOutline, buildOutlineTree,       // headings, ids, anchors
+  diffDocuments,                      // which blocks were added, removed, changed
+  validateDocument, sanitizeDocument, isEditorDocument,
+  isSafeUrl, sanitizeUrl, sanitizeMediaUrl,
+  textColorToCss, highlightToCss, TEXT_COLOR_TOKENS, HIGHLIGHT_TOKENS,
+} from "@x12i/editor";
+```
+
+All pure functions with typed options and warnings (`ConversionWarning`), safe to use in server code, workers
+and tests. `tiptapToDocument(documentToTiptap(doc))` returns an equal document for every block and mark.
+
+## Security
+
+- **URLs.** Links allow `http`, `https`, `mailto`, `tel` and relative paths. `javascript:`, `data:`, `vbscript:`
+  and friends are rejected in the editor, the converters, the view and the exporters. Only the `src` of
+  `image`, `video` and `audio` blocks additionally accepts `data:image/*` (so pasted or inline images work);
+  links, files and bookmarks never accept `data:`. Whitespace, control and invisible characters are removed
+  before the scheme is checked, so `java<TAB>script:` is rejected too. Links get `rel="noopener noreferrer"`.
+- **No raw styles.** Text color and highlight store a token path. Only tokens on the allow-lists in the
+  package render, as `var(--kit-...)`. A stored document cannot inject CSS.
+- **No raw HTML.** The React components never use `dangerouslySetInnerHTML`. `documentToHtml` escapes all text
+  and attributes and emits no inline styles or event handlers, so its output is safe to inject.
+- **Embedded renderers** are your code; the editor passes them only typed payloads, and catches their errors.
+- **Unknown data** (a newer block type, an unknown mark) is preserved and reported, never executed.
+- `sanitizeDocument` and `validateDocument` are there for documents from untrusted sources.
+
+## Limitations
+
+This is a complete editor, but not every feature of a large product. Honest list:
+
+- **Collaboration is a contract only.** `CollaborationProvider` is typed; there is no Yjs binding, presence or
+  remote cursors in this version.
+- **No drag handle.** Blocks move by keyboard (Alt+Shift+Up/Down), the block menu and the embed toolbar.
+- **No syntax highlighting** in code blocks (language is stored and shown, not colored).
+- **No mention picker.** Existing mentions render and round-trip; typing `@` does nothing yet.
+- **No math renderer.** Equations show their LaTeX source in a monospace block.
+- **Images by URL only.** No upload, drag-and-drop or paste-to-upload; `data:image` URLs are accepted.
+- **Tables:** no column resizing. Cell content is inline only in the stored format. Merged cells are
+  preserved (`colSpan`, `rowSpan`).
+- **Toggles open expanded** when a document loads; their open state is not stored.
+- **Slash menu queries cannot contain spaces:** typing a space closes the menu.
+- **Markdown export is lossy** for blocks Markdown cannot express (callout, toggle, columns, embeds are written
+  as readable fallbacks), and import follows GFM, where the first table row is the header.
+- `trailingNode` is disabled, so a document may end with a non-paragraph block such as a table or a divider.
+  Add a line with "Add paragraph below" in the block menu (`Mod+/`).
+- Extra `extensions` are read once, when the editor mounts.
+- Code block, `Document`, toggle and callout nodes are written in this package because Tiptap's code-block
+  package is not a direct dependency under strict pnpm resolution.
+
+## Licensing
+
+MIT. Only MIT-licensed Tiptap packages are used; no Tiptap Pro, cloud or paid extensions.